package com.gobang.service;

import java.util.Set;

/**
 * 连接管理服务接口
 * 负责WebSocket连接的生命周期管理、状态维护和会话管理
 * 
 * @author System
 * @since 1.0.0
 */
public interface ConnectionManagerService {
    
    /**
     * 添加用户连接
     *
     * @param userId 用户ID
     * @param sessionId WebSocket会话ID
     * @param username 用户名
     * @param currentScore 当前积分
     */
    void addConnection(Long userId, String sessionId, String username, Integer currentScore);
    
    /**
     * 移除用户连接
     *
     * @param userId 用户ID
     */
    void removeConnection(Long userId);
    
    /**
     * 根据会话ID移除连接
     *
     * @param sessionId WebSocket会话ID
     */
    void removeConnectionBySession(String sessionId);
    
    /**
     * 检查用户是否在线
     *
     * @param userId 用户ID
     * @return 是否在线
     */
    boolean isUserOnline(Long userId);
    
    /**
     * 获取用户的会话ID
     *
     * @param userId 用户ID
     * @return 会话ID，如果用户不在线返回null
     */
    String getUserSession(Long userId);
    
    /**
     * 根据会话ID获取用户ID
     *
     * @param sessionId 会话ID
     * @return 用户ID，如果会话不存在返回null
     */
    Long getUserIdBySession(String sessionId);
    
    /**
     * 更新用户最后活跃时间
     *
     * @param userId 用户ID
     */
    void updateLastActive(Long userId);
    
    /**
     * 更新用户状态
     *
     * @param userId 用户ID
     * @param status 用户状态（online/matching/gaming）
     */
    void updateUserStatus(Long userId, String status);
    
    /**
     * 获取用户状态
     *
     * @param userId 用户ID
     * @return 用户状态
     */
    String getUserStatus(Long userId);
    
    /**
     * 获取所有在线用户ID
     *
     * @return 在线用户ID集合
     */
    Set<Long> getAllOnlineUsers();
    
    /**
     * 获取房间内的用户列表
     *
     * @param roomId 房间ID
     * @return 用户ID集合
     */
    Set<Long> getRoomUsers(String roomId);
    
    /**
     * 将用户加入房间
     *
     * @param roomId 房间ID
     * @param userId 用户ID
     */
    void addUserToRoom(String roomId, Long userId);
    
    /**
     * 将用户从房间移除
     *
     * @param roomId 房间ID
     * @param userId 用户ID
     */
    void removeUserFromRoom(String roomId, Long userId);
    
    /**
     * 清理房间
     *
     * @param roomId 房间ID
     */
    void clearRoom(String roomId);
    
    /**
     * 获取超时的连接
     *
     * @param timeoutMs 超时时间（毫秒）
     * @return 超时的用户ID集合
     */
    Set<Long> getTimeoutConnections(long timeoutMs);
    
    /**
     * 清理超时连接
     *
     * @param timeoutMs 超时时间（毫秒）
     * @return 被清理的连接数量
     */
    int cleanTimeoutConnections(long timeoutMs);
} 